home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / msdos / nnans593.zip / NNANSI.DOC < prev    next >
Text File  |  1993-05-07  |  43KB  |  1,121 lines
  1.        NNANSI.COM-- Enhanced MS-DOS ANSI Console Driver
  2.              For EGA/VGA Displays
  3.  
  4. Note: MS-DOS and Windows are trademarks of Microsoft Corporation.
  5. PC/XT, PC/AT, and PS/2 are trademarks of IBM Corporation.
  6. 4DOS is a trademark of J.P. Software.
  7. MKS Toolkit is a trademark of Mortice Kern Systems Inc.
  8. PROCOMM is a trademark of Datastorm Technologies, Inc.
  9. Typing Tutor IV is a trademark of Kriya Systems, Inc.
  10. Desqview and QEMM are trademarks of Quarterdeck.
  11. 386MAX is a trademark of Qualitas.
  12.  
  13. Manufacturers' names are the trademarks of their respective manufacturers.
  14. That should take care of everyone.
  15.  
  16. Documentation for version 5/93.
  17.  
  18. This version of NNANSI contains the following improvements
  19. over NNANSI version 1/93:
  20.  
  21. 1. Improved support of DOS/V, the Japanese version of MS/DOS. (thanks, 
  22.    Akira Kikuchi!)
  23.  
  24. 2. BIOS Only configuration for use with speech synthesizers for the
  25.    visually impaired, and in BBS applications using Doorway (tm). This
  26.    mode is much slower, but allows operation of programs that require
  27.    printing via the BIOS to work properly.
  28.  
  29. 3. Corrected source code error when extended keyboard not used.
  30.  
  31. 4. A few enhancements made in some display card definitions.
  32.  
  33. IMPORTANT NOTE: the compiled NNANSI.COM is intended for 80286 or later
  34.    systems with "AT" style (12 function key) keyboards and VGA displays. You 
  35.    will need to recompile on systems that don't meet this requirement.
  36.  
  37.  
  38. *********INTRODUCTION
  39.  
  40. NNANSI.COM (version 5/93) is an improved version of NANSI.SYS
  41. (version 2.2), by Daniel Kegel, which is in turn such an improvement
  42. over ANSI.SYS that *no one* should be without one of these.
  43.  
  44. If you are using ANSI.SYS, be aware that either of these drivers
  45. will offer greatly improved performance and functionality over
  46. your current driver. Current users of NANSI.SYS with EGA or VGA
  47. displays (and other enhanced ANSI.SYS drivers) will notice still
  48. greater performance and functionality in NNANSI.SYS.
  49.  
  50. Even if you don't use an ANSI.SYS driver, you will achieve major 
  51. performance benefits. (Note that there will be no performance
  52. benefits for programs that write directly to the display).
  53.  
  54.  
  55. A short list of improvements of NANSI.SYS (version 3.0) over
  56. ANSI.SYS: 
  57.  
  58. 1. Intrinsic 43 or 50 line support (MS-DOS 4.0 now has this).
  59.  
  60. 2. Some additional text mode escape sequences: Insert Lines,
  61.         Delete Lines, Insert Characters, Delete Characters.
  62.  
  63. 3. Greater to *much* greater performance.
  64.  
  65. 4. Supports higher resolutions, both text and graphic modes.
  66.  
  67. 5. Graphic mode cursor
  68.  
  69. 6. Special configuration that uses the BIOS only for display.
  70.  
  71.  
  72. A short list of improvements of NNANSI.COM (version 5/93) over
  73. NANSI.SYS:
  74.  
  75. 1. Additional escape sequences: erase to start/end of display,
  76.         insert/delete lines in graphic modes, added Set Graphic
  77.         Rendition codes (and properly working reverse video,
  78.     underline, and invisible modes). Accurate ANSI escape 
  79.     sequence parsing
  80.  
  81. 2. Graphic cursor support is better, and can be disabled.
  82.  
  83. 3. Intrinsic support for both 43 and 50 line modes on a VGA. The
  84.     prompt command can be used to maintain 43 or 50 line display
  85.     modes. 40 column support for 43 and 50 line modes.
  86.  
  87. 4. Faster text mode performance; *much* faster scrolling
  88.         (when in "fast mode").
  89.  
  90. 5. Much faster performance in 640x350 to 800x600 16 color
  91.         graphic modes. Every ANSI control sequence (except
  92.         insert/delete characters and blink) work in these modes
  93.         as well.
  94.  
  95. 6. Readily configured for enhanced graphic and text modes of
  96.         various display cards. Support for several popular cards
  97.         are provided.
  98.  
  99. 7. Blink in 16 color graphics modes (up to 800x600) will exclusive-OR
  100.     characters.
  101.  
  102. 8. Support for MS-DOS V4.0 and later MODE commands, and properly
  103.     clears the display in enhanced modes using command.com's CLS.
  104.  
  105. 9. Driver can be loaded as TSR from the command line.
  106.  
  107. 10. Desqview aware.
  108.  
  109. 11. Supports Japanese DOS/V
  110.  
  111. On the other hand, NANSI is smaller, and works with MDA as distributed.
  112.  
  113.  
  114.  
  115. **********************LICENSE REQUIREMENTS
  116.  
  117. Daniel Kegel is the author of NANSI.SYS, of which this is a derived
  118. work. I, Tom Almy, think enough of his efforts and programming skills
  119. that I used NANSI.SYS as a base for NNANSI.COM. NANSI.SYS version 2.2
  120. came with sources and free distribution for personal or educational
  121. use, but prohibits commercial use.  I have an agreement with Mr.
  122. Kegel to license NNANSI.COM in accordance with his newest NANSI.SYS
  123. license arrangement:
  124.  
  125. "If you use this program for education or at home, you are
  126. encouraged to send a US$10 donation to the author.  If you use
  127. it for business purposes, you are required to purchase a
  128. right-to-use license by sending US$10 to the author."
  129.  
  130. Send contributions/user fees to:
  131.  
  132.         Daniel Kegel
  133.         535 E. Mendocino St
  134.         Altadena, CA  91001
  135.  
  136. You can also reach him at his internet address:
  137.  
  138. dank@blacks.jpl.nasa.gov
  139.  
  140.  
  141. Everyone wins with this arrangement!
  142.  
  143. * Commercial users can now legally use NNANSI.COM
  144.  
  145. * Personal users can show their gratitude.
  146.  
  147. * Daniel Kegel can make a little money for his efforts.
  148.  
  149. * I won't feel guilty for "ripping off" his work.
  150.  
  151.  
  152. I place no restrictions on my modifications to NANSI.SYS. I
  153. neither request nor will I accept any contributions for my work
  154. on this program. I made these modifications as part of an effort
  155. to understand the workings of DOS device drivers and the EGA/VGA
  156. display. 
  157.  
  158. On the other hand, I do like to hear from users, satisfied or
  159. (even) not satisfied. 
  160.  
  161.             I M P O R T A N T
  162. >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
  163. Please, if you have problems, check the PROBLEMS section of this
  164. document before contacting me. Greater than 90% of the problem
  165. reports I receive are answered in this section.
  166. <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  167.  
  168. My address is:
  169.  
  170.         tom.almy@tek.com        (Internet)
  171.  
  172. or
  173.  
  174.         Tom Almy
  175.         17830 SW Shasta Trail
  176.         Tualatin, OR 97062
  177.  
  178. I also now run a BBS at (503)-620-0307, 1200-9600 (v.32) bps
  179.  
  180. If you must use the postal service. Enclose a stamped, self-
  181. addressed envelope if you desire a reply.
  182.  
  183.  
  184. *********DISTRIBUTED FILES
  185.  
  186. The distribution has the following files:
  187.  
  188.     readme.1st    - READ THIS FIRST
  189.         nnansi.com      - Driver, with compilation options set as shown
  190.                         - in the file CONFIG.INC
  191.         nnansi.doc      - this file
  192.     howto.doc    - explaination about the different ways to
  193.               write to the display
  194.         gcon.bat        - turns graphic cursor on
  195.         gcoff.bat       - turns graphic cursor off
  196.         fast.bat        - turns fast mode on
  197.         slow.bat        - turns fast mode off
  198.     biosw.bat    - turns ANSI bios write_tty on
  199.     nobiosw.bat    - turns ANSI bios write_tty off
  200.     25.bat        - set 80x25 text mode
  201.     43.bat        - set 80x43 text mode
  202.     50.bat        - set 80x50 text mode (VGA only)
  203.     run.bat        - load NNANSI TSR as full function driver
  204.     norun.bat    - unload NNANSI TSR when loaded as full
  205.               function driver
  206.  
  207.     dtest.exe    - Performance testing program for ANSI drivers
  208.     stat.com    - Print out information about display status
  209.  
  210.         makefile        - for Don Kneller's NDMAKE
  211.         nnansi.asm      - The source file
  212.     config.inc    - Configuration selections (part of source)
  213.     drivers.inc    - Display specific macros (part of source)
  214.  
  215.  
  216.  
  217. *********INSTALLATION
  218.  
  219. NOTE: If you have an MDA (Monochrome or Hercules display adapter) you
  220. will need to reassemble NNANSI first. You will also need to
  221. reassemble if you are using DOS/V, an 8088 processor, an EGA display,
  222. or an original 84 key keyboard. You will probably want to reassemble
  223. to configure for your specific display card (if it is an "Enhanced"
  224. card), will not be using Desqview, are using a DOS prior to version
  225. 4.0, or otherwise want other defaults.
  226.  
  227. NNANSI installs just like ANSI.SYS (or NANSI.SYS), it is a device
  228. driver that you specify in your CONFIG.SYS file:
  229.  
  230.         DEVICE=NNANSI.COM
  231.  
  232. If you are using code pages, place this command before the 
  233. DEVICE=DISPLAY.SYS command, otherwise code pages will not work.
  234.  
  235. You can also load NNANSI as a TSR (Terminate and Stay Resident)
  236. program instead. To do this, add the following lines to your
  237. AUTOEXEC.BAT file:
  238.  
  239.     NNANSI D
  240.     CTTY CON
  241.  
  242. If you wish to load the driver as a TSR in Desqview or Windows, 
  243. see the section on "NNANSI as a TSR". You cannot use the D option,
  244. and the CTTY command is not needed but the driver will have limited
  245. features.
  246.  
  247. If NNANSI is the last TSR loaded, it can then be removed. See the
  248. section "NNANSI as a TSR" for the special technique necessary to
  249. remove NNANSI.
  250.  
  251. For optimum performance, run fast.bat and biosw.bat, but if
  252. applications have trouble with either of these, you will have to
  253. revert back to slower operating modes (read section "FAST MODE").
  254.  
  255. While the supplied compiled driver is suitable for most
  256. installations, you can get better results by customizing the driver
  257. for your display card. To do this you will need an assembler, such as
  258. Borland Turbo Assembler, a text editor, and (optionally) Don
  259. Kneller's NDMAKE program. I understand that Borland's MAKE will also
  260. work.
  261.  
  262. Some people have asked why I don't have command line options for
  263. the driver or a separate configuring program but require the user to
  264. use an assembler. The reasons:
  265.  
  266. 1. These make the driver larger and possibly slower than it needs to be.
  267.    If you insist on a full-featured display driver try FANSI-CONSOLE.
  268. 2. I feel that users who are sophisticated enough to be able to utilize
  269.    NNANSI either have an assembler or have access to one. This is not
  270.    a program for novices.  
  271. 3. I'm lazy. I'm not interested. I've got other things to do (which pay).
  272.  
  273. All options are specified in the file CONFIG.INC. Edit that
  274. file and make changes as appropriate. These descriptions assume
  275. the initial default settings:
  276.  
  277. DOSV    (FALSE)
  278.     Set true to use with DOS/V. This option will eliminate some of 
  279.         NNANSI's performance improvements. It forces the setting of no
  280.         EGA, no cheap_pc, and DESQVIEW. Insert character and delete
  281.         character ANSI commands will not function. Assumes a display
  282.         card capable of handling DOS/V V-text.
  283.  
  284. BIOS_ONLY (FALSE)
  285.     Set true for applications which require screen writes through the
  286.     BIOS. This option will eliminate most of NNANSI's performance
  287.         improvements. It forces the settings of no fast29, no
  288.         bios_write_tty, and DESQVIEW. In general, no other display hardware
  289.         selection should be made since this driver is intended for standard
  290.         EGA/VGA text modes only.
  291.  
  292. VEGA, PARADISE, STBVGA...  (all FALSE)
  293.         Set only one of these TRUE to match your enhanced
  294.         EGA/VGA display card. If you have a card not on the list
  295.         and experience problems with either blotches in enhanced
  296.         text mode or poor performance (unsettable background
  297.         colors is a clue) in graphics modes CONTACT THE AUTHOR.
  298.  
  299. VGA     (TRUE)
  300.         If you have an EGA display, set this to FALSE. You might
  301.         also want to set this to FALSE if you have a VGA and are
  302.         used to the ESC [=43h sequence giving 50 line mode.
  303.  
  304. EGA     (FALSE)
  305.         If you have an EGA, set this to TRUE.
  306.  
  307. MONO    (FALSE)
  308.     Must be TRUE if you have a Monochrome Display Adapter (MDA)
  309.     or Hercules card either as your sole display or in addition
  310.     to a color display controller. If you don't, leave this FALSE
  311.     as it both hurts performance and enlarges the driver. You cannot
  312.     use an MDA with Desqview and NNANSI at the same time.
  313.  
  314. TSR    (set on tasm command line)
  315.     If TRUE, compiles TSR/DRIVER COM file version, otherwise compiles 
  316.     DRIVER only, SYS file version.
  317.  
  318. DESQVIEW (TRUE)
  319.     If TRUE, and TSR is TRUE, compiles DESQVIEW awareness code.
  320.     If you don't intend to use DESQVIEW you should set this to
  321.     FALSE.
  322.  
  323. VESA    (FALSE)
  324.     Set TRUE if you have a VESA compatible display card BIOS.
  325.     You will also need to have a particular display specified
  326.     for best results. VESA has been successfully tested with
  327.     a Diamond Speedstar card (TSENG4000 set TRUE) and using
  328.     Diamond's VESA BIOS extension, and with a Diamond Steath
  329.         with built in VESA support. When using built in VESA, there
  330.     seems to be a problem in selecting graphics modes via their
  331.     VESA mode numbers.
  332.  
  333.  
  334. BAD_ERASE    (FALSE, except if TSENG4000 selected)
  335.     Set to true if erase to end of line and erase to start/end of
  336.         screen erase the wrong portion of the display
  337.  
  338. cheap_pc (FALSE)
  339.         Set to FALSE for "PC/AT" and "PS/2" class machines which
  340.     have 80186 or greater processors.
  341.  
  342. ext_keybd (TRUE)
  343.     Set to TRUE for "PC/AT" and "PS/2" class machines with 101+ key
  344.     keyboards (the kind with 12 function keys and separate cursor keys
  345.     from the numeric pad).
  346.  
  347. key_redef (FALSE)
  348.         Set to TRUE if you use key redefinition. There are
  349.         Trojan Horse programs that take advantage of this
  350.         feature, and most people don't use it anyway, so the
  351.         default is FALSE.
  352.  
  353. init_buffer_size (256)
  354.         Enlarge if you use key redefinition and don't have
  355.         enough room.
  356.  
  357. quick_char (TRUE)
  358.         Faster graphics display in 16 color modes, at cost of
  359.     much extra code since this involves added display
  360.     routines. Must be TRUE if gbackground is also TRUE.
  361.  
  362. fast29  (TRUE)
  363.         Makes int29 display calls (used by DOS) 15% faster at a
  364.         cost of about 100 bytes.
  365.  
  366. bios_write_tty (TRUE)
  367.         The write tty BIOS call is taken over. It will now
  368.         perform faster and understand ANSI escape sequences. This
  369.     latter feature can be a mixed blessing. This feature can be
  370.     disabled at runtime if it is assembled in.
  371.  
  372. gbackground (TRUE)
  373.         Enables setting of non-black background color in 16 color
  374.     graphic modes (640x350 to 800x600 resolutions). If set to
  375.     TRUE, quick_char must also be set to TRUE. If this feature is
  376.     not desired, it is possible (depending on the system) to get
  377.     greater performance by defining both gbackground and
  378.     quick_char FALSE. This will also save quite a bit of
  379.     code. Experiment and see for yourself.
  380.  
  381. dos4 (TRUE)
  382.         Under MS/PC DOS version 4.0 (and 5.0) allows command.com and
  383.     mode.com to recognize NNANSI as an ANSI driver. If you are
  384.     using older DOS versions, you can define this to be FALSE.
  385.  
  386. initgc  (FALSE)
  387.         Graphic mode cursor is initially off. You can turn it on/off
  388.     with a control sequence.
  389.  
  390. initfast (FALSE)
  391.         Fast scroll mode is initially off. This also means that
  392.         multiple page support is initially on. You can turn it on/off
  393.     with a control sequence, and there are other work-arounds as
  394.     well.
  395.  
  396. initbiosw (FALSE)
  397.     ANSI bios write_tty is initially off. You can turn it on/off
  398.     with a control sequence.
  399.  
  400.  
  401. You can then either use the supplied makefile to generate a new
  402. nnansi.sys/nnansi.com or assemble manually as shown (Borland tools
  403. illustrated): 
  404.  
  405. tasm /m5 /DTSR=0 nnansi          (Use /m5 for version 2.0 or later)
  406. tlink nnansi,nnansi.sys/m/t     (generates nnansi.sys for config.sys)
  407.  
  408. tasm /m5 /DTSR=1 nnansi
  409. tlink nnansi,nnansi.bin/m/t    (generates nnansi.com for config.sys
  410. rename nnansi.bin nnansi.com     or TSR use)
  411.  
  412. The .sys driver offers no advantages other than it takes less memory
  413. while loading (this might be a consideration with some high memory
  414. management programs). For this reason, a .sys version is no longer
  415. distributed.
  416.  
  417.  
  418. IMPORTANT NOTE FOR USERS OF BORLAND TURBO ASSEMBLER V3.0: 
  419.  
  420. There is a bug in this version which causes the assembler to hang
  421. when assembling the sys version of NNANSI. The solution is to only
  422. build the com version. The bug is fixed with V3.1.
  423.  
  424.  
  425. NOTE FOR MICROSOFT MASM USERS:
  426.  
  427. With the Microsoft assembler, you will need to make some changes to
  428. the source to avoid the branch out of range errors, and you will need
  429. to use the exe2bin program to convert the linker generated exe file
  430. into a binary image file, which you then have to rename to
  431. NNANSI.SYS or NNANSI.COM.
  432.  
  433. To correct the branch out of range, you will need to replace the conditional
  434. branch with an conditional branch of the opposite sense around an
  435. unconditional branch to the same destination. Example:
  436.  
  437.     jne    foo    ; original statement, now "out of range"
  438.  
  439. becomes:
  440.  
  441.     je    new_label
  442.     jmp    foo
  443. new_label:
  444.  
  445.  
  446. You will also need to delete the first few lines in NNANSI.ASM, which
  447. are directives for the Borland Assembler.
  448.  
  449.  
  450. **************NNANSI AS A TSR**
  451.  
  452. NNANSI can now be loaded as a TSR in two modes, limited and full. If
  453. you intend to use NNANSI as a TSR, such as in a Desqview window, or
  454. for temporary use, please read this section carefully.
  455.  
  456.  
  457. To load NNANSI in full driver mode, execute the following two commands
  458. (or execute run.bat):
  459.  
  460. nnansi d
  461. ctty con
  462.  
  463. This will load the driver such as it runs identically to NNANSI loaded
  464. as a driver in CONFIG.SYS. This means that not only does it take control
  465. of several interrupt vectors, the driver is also linked into the DOS
  466. driver chain. The CTTY command is necessary to force command.com to 
  467. "reopen" its console interface to use the NNANSI driver.
  468.  
  469. This method must not be used within a multitasking environment such
  470. as Microsoft Windows or Desqview, because the relinking of the driver
  471. chain corrupts system integrity. However it may be used to load
  472. NNANSI before running Windows. In the Desqview case, a batch file can
  473. be used to unload NNANSI, run Desqview, and then reload NNANSI when
  474. finished.
  475.  
  476. Within each DOS window in Windows or Desqview, the limited version of the
  477. NNANSI TSR can be loaded (described below). The copy of NNANSI should
  478. be unloaded before closing the DOS window.
  479.  
  480. NNANSI in full driver mode can be unloaded using the following procedure
  481. providing it is the last TSR loaded, you are not "shelled out" of a program,
  482. are running the same instance of COMMAND.COM, and did not load NNANSI
  483. "high" using QEMM, 386/MAX, or DOS 5.0. From a batch file, execute:
  484.  
  485. @echo off
  486. nnansi u
  487. ctty con
  488.  
  489. The ctty command must be executed immediately after the NNANSI command,
  490. otherwise the system may "crash". The batch file norun.bat is provided
  491. to unload NNANSI.
  492.  
  493. Note that full driver mode NANNSI must be uninstalled using NNANSI, and
  494. not with a TSR management program. Such programs are incapable of
  495. unchaining NNANSI from the device driver list.
  496.  
  497. --------------------
  498.  
  499. NNANSI also has a limited TSR mode. In this mode the driver is not
  500. linked into the DOS driver chain. To load NNANSI in limited mode execute:
  501.  
  502. nnansi
  503.  
  504. In limited mode the device status report will not function, nor will
  505. keyboard key reassignment. The DOS MODE command will not change the
  506. number of display lines either. Also the performance improvement for
  507. RAW mode (which gives NNANSI its greatest performance) will not be
  508. available.
  509.  
  510. You can unload NNANSI which has been loaded in limited mode by executing:
  511.  
  512. nnansi u
  513.  
  514.  
  515. The limited TSR mode driver can be used in a Microsoft Windows or Desqview
  516. window without problems. You can also uninstall the limited mode driver
  517. with a TSR management program.
  518.  
  519.  
  520.  
  521. **************HOW MUCH PERFORMANCE IMPROVEMENT IS THERE?
  522.  
  523. I have performed considerable testing on an EVEREX 25Mhz 80386
  524. machine with a Video 7 (Headland) Fastwrite VGA display controller
  525. (and its BIOS), under both DOS 3.3 and 4.0. Your results will
  526. probably vary, and BIOS performance without NNANSI will also improve
  527. if the EGA/VGA BIOS is copied to RAM as supported by some vendors and
  528. also possible with QEMM or 386/MAX on 80386 based systems.
  529.  
  530. Performance is proportional to roughly independent factors, writing
  531. speed and scrolling speed. Writing speed is the rate at which
  532. characters can be drawn on the display without the display scrolling.
  533. Scrolling speed is the rate at which the display can scroll (no
  534. new characters are drawn). Writing speed tends to be independent of
  535. display mode (except graphic modes are slower), while scrolling speed
  536. tends to be proportional to the number of character positions on the
  537. display (except for NNANSI fast mode, which is independent of screen
  538. size). 
  539.  
  540. When using ANSI.SYS rather than no driver at all, there is roughly a
  541. 2.3x degradation in performance for writing. Scrolling performance
  542. improves 44% when DOS 4.0 ANSI driver is used, but remains unchanged
  543. with the DOS 3.3 driver.
  544.  
  545. Compared to no driver, NANSI.SYS (3.0) is 3x to 3.5x faster for
  546. writing, and is roughly 45x faster when writing using DOS in RAW
  547. mode. It is roughly 2x faster scrolling.
  548.  
  549. Compared to the no driver or other ANSI drivers, NNANSI is 4x faster
  550. in BIOS TTY write calls. 
  551.  
  552. Compared to NANSI.SYS it is 2x faster in INT29 calls, 73% faster in
  553. DOS write calls, but there is no speedup in RAW mode. When fast mode
  554. is used, scrolling is 15x to 25x faster.
  555.  
  556. This means that text mode programs that take advantage of RAW
  557. mode and buffering can display 100 times faster with NNANSI (and
  558. without scrolling, NANSI) over ANSI.SYS. It works out to about
  559. 420,000 characters per second with my fast machine.
  560.  
  561. NNANSI also has speedups for 16 color graphic modes with resolutions
  562. between 640x350 and 800x600. With the graphic cursor turned on, the
  563. TTY BIOS call is about 10% slower than the standard BIOS call (which
  564. doesn't display a cursor), but other output calls are 2.5x to 3.5x
  565. faster than that of NANSI.SYS. Turning the graphics cursor off
  566. roughly doubles the writing speed of all modes but RAW.
  567.  
  568.  
  569.  
  570. **************FAST MODE  **READ THIS!!**
  571.  
  572. To get maximum speed, NNANSI has what I call Fast Mode. In text
  573. mode, there is more display memory than there are character on
  574. the display. Normally, the BIOS supports display "pages" that you
  575. can switch among. Changing the display page changes the region
  576. of the display memory that is sent to the display. Fast Mode
  577. uses the same technique (changing the starting location of the
  578. viewable memory region) to scroll the display upwards. 
  579.  
  580. Programs that make use of multiple display pages and scroll the
  581. display require that fast mode be turned off. Many debugging programs
  582. use two pages to maintain separate debugging and application
  583. displays. Some of the programs will still work in fast mode if they
  584. have a "swap screens" option ("-ds" for Borland Turbo Debugger, for
  585. instance).
  586.  
  587. A number of programs that directly access the display don't work if
  588. starting address has changed. These programs may not work properly in
  589. fast mode (or for that matter in display pages other than the first).
  590. NNANSI tries its best to work with these programs by resetting the
  591. display start location if any program does the "get display mode" or
  592. "scroll/clear display" BIOS calls. These calls are typically done by
  593. potentially offending applications when they start. As long as the
  594. display never scrolls under NNANSI control everything will work fine.
  595. A typical problem occurs in programs that have DOS or "shell escape"
  596. commands. If the DOS sub-shell (invocation of COMMAND.COM) causes the
  597. display to scroll, then upon exiting the sub-shell the display will
  598. be ruined. The solution to this problem (other than not using fast
  599. mode) is to clear the screen just before exiting the sub-shell.
  600.  
  601. Please note that Windows 3.0 in Enhanced Mode has problems with DOS
  602. applications running in a window using NNANSI's fast mode. You will
  603. need to run Windows with NNANSI in slow mode.
  604.  
  605. Some offending programs can be "fixed" by invoking them from a
  606. batch file (or alias if you use MKS Toolkit, 4DOS, ANARKEY...)
  607. which first clears the screen. Or you can use a batch file which
  608. turns off fast mode, then turn fast mode back on again after
  609. program execution. Example:
  610.  
  611. echo ^[[=98l
  612. offendingpgm %1 %2 %3 %4 %5
  613. echo ^[[=98h
  614.  
  615. Where "^[" is the escape (code 27) character.
  616.  
  617. Batch programs have been provided to enable (fast.bat) and disable
  618. (slow.bat) fast mode.
  619.  
  620.  
  621. NNANSI can also speed up programs that use BIOS calls for writing
  622. characters. NNANSI adds the ANSI features to such calls, which can
  623. cause problems with some applications. This feature is turned off by
  624. default, but can be enabled via an ANSI sequence or by executing the
  625. supplied batch file biosw.bat. The feature can be disabled with
  626. nobiosw.bat.
  627.  
  628.  
  629. ******************WRITING PROGRAMS FOR BEST PERFORMANCE
  630.  
  631.  
  632. To get best performance in programs you write, you must put the
  633. display in RAW mode, and buffer output.
  634.  
  635. In assembler, you can set raw mode with the following sequence
  636. (adapt this for other languages):
  637.  
  638.         mov     ax,4400h        ; get device status
  639.         mov     bx, 1           ; of device 1 (standard output)
  640.         int     21h
  641.         xor     dh, dh          ; clear upper byte
  642.         mov     saved_state, dx ; save it for later
  643.         mov     ax, 4401h       ; set new status
  644.         or      dl, 20h         ; with raw bit set
  645.         int     21h
  646.  
  647. Reset raw mode before terminating the application:
  648.  
  649.         mov     ax, 4401h       ; set status to original values
  650.         mov     bx, 1
  651.         mov     dx, saved_state
  652.         int     21h
  653.  
  654. There is a fixed amount of overhead (and it is high) for each
  655. DOS call. Therefore you should buffer up write requests into a
  656. single call. With the C language, you can use the setvbuf() call
  657. to set a large buffer size.
  658.  
  659. Even if you don't follow this advice, you will get a major
  660. performance improvement over ANSI.SYS (or no device driver at
  661. all). 
  662.  
  663. Programs using RAW mode and buffering easily beat the
  664. performance of the supposedly high speed console drivers
  665. supplied in Turbo C and Microsoft C. And by using ANSI control
  666. sequences your programs can be made portable to other systems!
  667.  
  668.  
  669. *****************TYPICAL PROBLEMS
  670.  
  671.  
  672. ALSO READ THE SECTION "FAST MODE"
  673.  
  674.  
  675. SYSTEM CRASHES UPON BOOTING, OR DISPLAY BADLY CORRUPTED EVEN IN
  676. STANDARD 80x25 TEXT MODE.
  677.  
  678. You have assembled NNANSI with cheap_pc set to FALSE on an 8088 based
  679. system, or you are trying to use NNANSI on an MDA or Hercules
  680. Graphics equipped system without reassembling with MONO equal TRUE.
  681.  
  682. This can also happen if you are using DOS/V with NNANSI not compiled for
  683. DOS/V operation.
  684.  
  685.  
  686. KEYBOARD IS "LOCKED"
  687.  
  688. You have set ext_keybd TRUE when you have an original style (10 function
  689. key) keyboard, or a BIOS that does not support the extended keyboard.
  690.  
  691.  
  692. ON A VGA, SETTING 43 LINE MODE GIVES 43 LINES, WHEN IT GAVE 50
  693. WITH AN OLDER VERSION OF NNANSI.SYS OR WITH NANSI.SYS
  694.  
  695. This is correct. There is now a new setting for 50 line mode. If
  696. you require that 43 line mode give 50 lines, recompile the
  697. system with VGA set to FALSE.
  698.  
  699.  
  700. I USED AN EARLIER VERSION OF NNANSI, AND NOW I FIND THAT NNANSI IS
  701. MUCH SLOWER THAN BEFORE
  702.  
  703. The defaults have changed. You now have to run FAST and BIOSW for
  704. fastest operation.
  705.  
  706.  
  707. I USED AN EARLIER VERSION OF NNANSI, AND NOW FIND MY DISPLAY 
  708. INEXPLICABLY CHANGING MODES
  709.  
  710. The commands for graphic cursor, fast mode, and line wrap are 
  711. more restrictive. Use the new batch files for fast, slow, gcon, and
  712. gcoff, and change any code of your own appropriately.
  713.  
  714.  
  715. ON A VGA, SETTING 50 LINE MODE CAUSES VERY STRANGE BEHAVIOR
  716.  
  717. Two possibilities. Your display adapter is really an EGA, or you
  718. have compiled NNANSI with VGA set to FALSE. In the latter
  719. case, you can get 50 line mode by setting 43 line mode, while in
  720. the former case you can't get 50 line mode at all.
  721.  
  722.  
  723. ON A VGA, AFTER LEAVING 43/50 LINE MODE THE CURSOR IS IN THE
  724. MIDDLE OF THE CHARACTER BLOCK
  725.  
  726. Recompile the driver with EGA set to FALSE.
  727.  
  728.  
  729. ON AN EGA, THE CURSOR DISAPPEARS IN 43 LINE MODE WHEN RUNNING
  730. SOME APPLICATIONS
  731.  
  732. There is nothing you can do, as this is caused by an error in
  733. the design of the EGA BIOS.
  734.  
  735.  
  736. IN 43/50 LINE MODE, THE DOS CLS COMMAND ONLY CLEARS THE FIRST 25
  737. LINES OF THE DISPLAY (DOS 4.0)
  738.  
  739. Reassemble with "dos4 EQU TRUE", as it is in the distribution NNANSI
  740. driver.
  741.  
  742.  
  743. DISPLAY SHOWS UGLY BLOCKS AT THE START AND END OF EACH LINE OR
  744. PERFORMANCE SLOWS GREATLY IN EXTENDED (GREATER THAN 80X25) TEXT MODES 
  745.  
  746. Your display controller sets the display mode byte in the BIOS to
  747. some value other than "3". You can either set the byte (at location
  748. 40:49h) back to 3 after setting the display mode, or configure NNANSI
  749. to know about these special modes. This problem is typical for most
  750. cards, it seems. There may already be a proper configuration for your
  751. display in CONFIG.INC. 
  752.  
  753.  
  754. DISPLAY IS NOTICEABLY SLOWER WRITING OR CANNOT SWITCH BACKGROUND
  755. COLORS IN EXTENDED (GREATER THAN 640x480, OR 640x350 EGA)
  756. GRAPHIC MODES
  757.  
  758. In 256 color modes or 1024x768 modes, the background color cannot be
  759. changed. In other modes, you will need to configure NNANSI for your
  760. display card.  Look for a proper configuration in CONFIG.INC.
  761.  
  762.  
  763. DISPLAY GOES BLANK WHEN STARTING AN APPLICATION. DISPLAY SHIFTED
  764. PARTLY OFF SCREEN WHEN STARTING AN APPLICATION. DISPLAY
  765. DISAPPEARS DURING EXECUTION OF A APPLICATION.
  766.  
  767. First try clearing the screen before execution. If that doesn't
  768. work, leave fast mode (see preceding section on FAST MODE).
  769.  
  770.  
  771. FUNNY BLOTCHES OCCASIONALLY APPEAR AT VARIOUS POINTS IN A
  772. GRAPHIC APPLICATION
  773.  
  774. This is the graphics cursor. You can disable it either by
  775. reconfiguring the driver, or by sending the control sequence to
  776. disable the graphics cursor. A batch file, GCOFF.BAT, has been 
  777. provided for this purpose.
  778.  
  779.  
  780. TEXT DISPLAY IS MESSED UP, POSSIBLY CHANGING COLORS IN UNUSUAL
  781. PLACES. 
  782.  
  783. This has been observed with programs using the BIOS for writing
  784. to the display, and not expecting the ANSI translation (or the
  785. conversion of the TAB character into spaces instead of a special
  786. graphic). Execute NOBIOSW.BAT to turn the ANSI translation off
  787. for these programs.  PROCOMM and Typing Tutor IV have this problem.
  788.  
  789.  
  790. CANNOT SET VESA STANDARD EXTENDED DISPLAY MODES
  791.  
  792. You must compile the driver with VESA defined as TRUE, and then
  793. must request a mode 128 less than that really desired. There are also
  794. problems with boards having built-in VESA support without using a software
  795. VESA driver; for these boards you will need to set the display mode using
  796. the mode changing software supplied by the vendor.
  797.  
  798.  
  799. THE MODE COMMAND DOES NOT CHANGE THE NUMBER OF DISPLAY LINES
  800.  
  801. The mode command does not function if NNANSI is loaded as a limited
  802. TSR -- install as a full TSR or as a device driver. Also, you might
  803. need to reassemble with "dos4 EQU TRUE", as it is in the distribution
  804. NNANSI driver. 
  805.  
  806.  
  807. A TSR OR REMOTE OPERATION PROGRAM DOES NOT WORK WITH NNANSI BUT DOES WITH ANSI
  808.  
  809. NNANSI is incompatible with programs that expect the ANSI driver to
  810. write to the display using BIOS calls. I recommend the use of the
  811. program ANSI.COM, from PC Magazine, for these uses.
  812.  
  813.  
  814. I USE 4DOS AND CANNOT ALIAS F11 AND F12
  815.  
  816. You need to recompile with ext_keybd set to TRUE.
  817.  
  818.  
  819. THE KEYBOARD REASSIGNMENT COMMAND DOES NOT SEEM TO BE WORKING
  820.  
  821. By default it is disabled to prevent "ANSI BOMBS". You will need to 
  822. recompile with key_redef set to TRUE.
  823.  
  824.  
  825.  
  826. *****************NNANSI COMMAND SEQUENCES
  827.  
  828. Command sequences start with the escape character (code 27,
  829. referred to in this section as ESC). NNANSI buffers up the
  830. sequence until it has a command to execute. If the sequence is
  831. not a valid command, the entire sequence is passed to the display.
  832.  
  833. All command sequences have the following format:
  834.  
  835.    ESC [ param1; param2; ...; paramN cmdchar
  836.  
  837. where
  838.        ESC     is the escape character
  839.        [       is the left bracket character.
  840.        param   are ascii decimal numbers or quoted strings.
  841.        cmdchar is the command character
  842.  
  843. No spaces are allowed within the command.
  844.  
  845. Missing arguments are defaulted to "1" unless otherwise specified
  846. (SGR, ED, and IBMKKR).
  847.  
  848. Quoted strings may use either single or double quote characters
  849. as delimiters. Each character inside the quoted string is
  850. converted to a numeric parameter. Quoted strings are only useful
  851. for the questionable Keyboard Key Reassignment command.
  852.  
  853.  
  854.  
  855.                    CURSOR POSITIONING COMMANDS
  856.  
  857. NAME    DESCRIPTION             COMMAND
  858. CUP     cursor position         ESC[y;xH
  859. HVP     cursor position         ESC[y;xf
  860.  
  861.         Either of these set the cursor position. CUP should be
  862.         used since HVP has other connotations not implemented in
  863.         NNANSI (or ANSI.SYS). The origin (in the upper left
  864.         corner) is x=1, y=1.
  865.  
  866. CUU     cursor up               ESC[nA
  867. CUD     cursor down             ESC[nB
  868.         n = # of lines to move. You cannot move beyond the edge
  869.         of the display.
  870.  
  871. CUF     cursor forward          ESC[nC
  872. CUB     cursor backward         ESC[nD
  873.         n = # of columns to move. You cannot move beyond the
  874.         edge of the display.
  875.  
  876. DSR     Device Status Report    ESC[6n
  877.         Find out cursor position. The driver responds with a
  878.         cursor position report (CPR) of the form "ESC[y;xR"
  879.         followed by a carriage return, as if typed at the
  880.         keyboard. 
  881.  
  882. SCP     Save Cursor Position    ESC[s
  883. RCP     Restore Cursor Position ESC[u
  884.         Cannot be nested.
  885.  
  886.  
  887.  
  888.  
  889.                         EDITING COMMANDS
  890.  
  891. NAME    DESCRIPTION             COMMAND
  892. ED      Erase in Display        ESC[nJ
  893.         n=0 or missing: Erase to end of screen (not in ANSI.SYS)
  894.         n=1: erase to start of screen (not in ANSI.SYS)
  895.         n=2: erase entire screen, and home cursor
  896.         Note: there is a bug in ANSI.SYS that performs function
  897.         2 regardless of the value of n. This bug is not repeated
  898.         in NNANSI because of the extra functionality provided.
  899.     Everybody's "ANSI.SYS" homes the cursor, which the standard
  900.     does not call for, and NNANSI keeps up that tradition.
  901.  
  902. EL      Erase in Line           ESC[K
  903.         Erases from cursor to end of line.
  904.  
  905. IL      Insert Lines            ESC[nL 
  906.         Inserts n blank lines at the line containing the cursor.
  907.         While the cursor line moves down, the cursor position is
  908.         unchanged. Not in ANSI.SYS. 
  909.  
  910. DL      Delete Lines            ESC[nM  
  911.         Deletes n lines, starting at the line containing the
  912.         cursor. The cursor is not moved. Not in ANSI.SYS
  913.         
  914. ICH     Insert Characters       ESC[n@  
  915.         Inserts n blank characters at cursor position. The
  916.         cursor does not move. Not in ANSI.SYS. Does not work in
  917.         graphic modes.
  918.  
  919. DCH     Delete Characters       ESC[nP  
  920.         Deletes n characters at the cursor. The cursor does not
  921.         move. Not in ANSI.SYS. Does not work in graphic modes.
  922.  
  923.  
  924.  
  925.  
  926.                   SET GRAPHIC RENDITION COMMAND
  927.  
  928. NAME    DESCRIPTION             COMMAND
  929. SGR     Set Graphics Rendition  ESC[n;n;...nm
  930.  
  931. The Set Graphics Rendition command is used to select foreground
  932. and background colors or attributes.  When you use multiple
  933. parameters, they are executed in sequence, and the effects are
  934. cumulative.  You can set all colors and attributes in any text
  935. mode.  In 16 color graphic modes between 640x350 and 800x600
  936. pixels you can set all colors and attributes except for blink.
  937. "Blink" becomes exclusive-OR character mode (very useful!).  You
  938. can set foreground colors, blink, and bold, only, in other 16 color
  939. modes.  Setting colors does not work correctly for other color
  940. modes -- make sure display is in the normal white on black mode
  941. before changing to these modes.
  942.  
  943. When a Monochrome Display Adapter (MDA) is used, foreground and
  944. background colors other than black and white should not be set. The
  945. MDA also ignores the underscore and bold attributes while in reverse
  946. video.
  947.  
  948. If no arguments are given, a single "0" argument is assumed. If multiple
  949. arguments are given, missing arguments are taken to be "0".
  950.  
  951.  
  952. Code          Value
  953. 0               All attributes off (normal white on black)
  954. 1               Bold
  955. 2               Dim (not Bold)
  956. 4               Underscore (emulated via blue foreground in CGA/EGA/VGA)
  957. 5               Blink (or EXOR -- see above)
  958. 7               Reverse Video (improved implementation over ANSI)
  959. 8               Invisible (improved operation -- foreground color
  960.         forced to background color, other attributes suppressed)
  961. 22              Cancel Bold
  962. 24              Cancel Underline (white foreground)
  963. 25              Cancel Blink
  964. 27              Cancel Reverse video
  965. 28        Cancel Invisible
  966. 30-37           foreground black/red/green/yellow/blue/magenta/cyan/white
  967. 40-47           background black/red/green/yellow/blue/magenta/cyan/white
  968.  
  969. Codes 2, 22, 24, 25, 27, and 28 are not in ANSI.SYS.
  970.  
  971.  
  972.  
  973.                     SET DISPLAY MODE COMMAND
  974.  
  975. NAME    DESCRIPTION             COMMAND
  976. SM      Set Mode                ESC[=nh
  977. RM      Reset Mode              ESC[=nl
  978.  
  979. The set and reset mode commands are identical in this context.
  980.  
  981. The BIOS supports many video modes. The code given for the AL
  982. register to the BIOS set mode command is used as the parameter to
  983. this set mode command. That means that extended modes that are
  984. settable in this manner can use this command. As an example, with the
  985. Diamond Speedstar, the command ESC[=34h will set 132 column by 44 row
  986. mode. Display cards that use other techniques to change display mode
  987. are left as an exercise to the user, but if you can get the card into
  988. an extended mode, NNANSI can used it (possibly with a configuration
  989. change, though).
  990.  
  991. VESA Display Cards: To set VESA modes, select a mode 128 less than the
  992. desired mode number. For instance, for 132x43 text mode, select mode
  993. 138 (rather than 266). 
  994.  
  995. Monochrome Display Adapter (MDA): These commands are ignored when the
  996. MDA is in use.
  997.  
  998. In the graphic modes, the cursor can be simulated with a blob
  999. (the character produced with character code 22).
  1000.  
  1001. Mode Code       Value
  1002.     0,1         text 40x25 16 color
  1003.     2,3         text 80x25 16 color
  1004.     4,5         graphics 320x200 4 color
  1005.     6           graphics 640x200 Black & White
  1006.     7        cursor wrap (see SET DISPLAY ATTRIBUTES, below)
  1007.     13          graphics 320x200 16 color, VGA only
  1008.     14          graphics 640x200 16 color, VGA only
  1009.     16          graphics 640x350 16 color, VGA only
  1010.     17          graphics 640x480 Black & White, VGA only
  1011.     18          graphics 640x480 16 color, VGA only
  1012.     19          graphics 300x200 256 color, VGA only
  1013.     43          43 line mode for modes 0-3 (Not in ANSI.SYS)
  1014.     50          50 line mode for modes 0-3 (VGA only, not in
  1015.                 ANSI.SYS)
  1016.     n           When not in above list, sets mode n. (Not in
  1017.                 ANSI.SYS) 
  1018.  
  1019.  
  1020. The modes marked as VGA only are not supported by ANSI.SYS
  1021. that comes with version 3.3 MS-DOS or earlier.
  1022.  
  1023. The 43 line and 50 line support reprograms the display to use smaller
  1024. characters. You must be in mode 3 (80x25) or 1 (40x25) for this
  1025. command to work. Set any other mode to leave 43/50 line mode. Unlike
  1026. early version of NNANSI and other drivers, reselecting  the same line
  1027. number mode (mode 3 (or 1), 43, or 50) will not cause the display to
  1028. clear. This makes it possible to put a 43 (or 50) line command within
  1029. the dos prompt to force this mode upon entering or returning to DOS.
  1030. For example, you can have 43 line mode automatically selected at the
  1031. DOS prompt by issuing this command:
  1032.  
  1033.     prompt $e[=43h$p$g
  1034.  
  1035. Unlike earlier versions of NNANSI, and NANSI.SYS, setting 43 line
  1036. mode on a VGA will give 43 (not 50) lines. You must use the explicit
  1037. 50 line mode command to get 50 lines on a VGA. If you would rather
  1038. have compatibility with these other, earlier drivers, recompile the
  1039. driver with VGA set to FALSE.
  1040.  
  1041. Under MS/PC DOS Version 4.0 (and later), the number of lines can
  1042. also be set using the MODE command. For instance, to set 43 line mode
  1043. under DOS 4.0, issue the command:
  1044.  
  1045.     mode con lines=43
  1046.  
  1047. Note that in older versions of NNANSI, and NANSI.SYS, the use of
  1048. the = character in the command was optional, and a ? could be used
  1049. instead. That is not true for this version.
  1050.  
  1051.  
  1052.                      SET DISPLAY ATTRIBUTES
  1053.  
  1054. NAME    DESCRIPTION             COMMAND
  1055. SM      Set Mode                ESC[?nh
  1056. RM      Reset Mode              ESC[?nl
  1057.  
  1058. Valid attributes that can be set and reset:
  1059.  
  1060. 7       Cursor Wrap     When false, cursor sticks at end of
  1061.                         line, rather than wrapping
  1062.  
  1063. 97    ANSI Bios    When true, calls of the bios write_tty
  1064.                         function will be processed by NNANSI,
  1065.             allowing processing of ANSI escape sequences.
  1066.             When false, processing will not occur. Some
  1067.             programs will not work properly if set to true.
  1068.  
  1069. 98      Fast Scroll     When true (fast mode) the starting
  1070.                         display location is changed for fast
  1071.                         scrolling, which can cause problems for
  1072.                         some programs. When false, the starting
  1073.                         location does not change and the
  1074.                         multi-page support is enabled.
  1075.  
  1076. 99      Graphic cursor  When true the cursor is displayed in
  1077.                         graphic modes. Some programs produce ghost
  1078.             cursors when set to true.
  1079.  
  1080. Batch files are supplied to change attributes 97, 98, and 99.
  1081.  
  1082. Note that the Fast Scroll attribute does not apply to the Monochrome
  1083. Display Adapter (MDA). Also note that in older versions of
  1084. NNANSI, and NANSI.SYS, the use of the ? character in the command
  1085. was optional, and an = could be used instead. That is not true for
  1086. this version. Because some Microsoft documentation claims that the
  1087. = character can be used for Cursor Wrap, NNANSI still supports that
  1088. bug.
  1089.  
  1090.  
  1091.  
  1092.                   KEYBOARD REASSIGNMENT COMMAND
  1093.  
  1094. This command is absent by default. You must recompile to enable
  1095. this command. Use of this feature is not recommended.
  1096.         
  1097. NAME    DESCRIPTION             COMMAND
  1098. IBMKKR  Keyboard Key Reassign   ESC[param;param;...;param p
  1099.  
  1100. If no parameters are given, all keys are reset. This is not true
  1101. for ANSI.SYS.
  1102.  
  1103. The first parameter is the key to reassign. IBM function keys take
  1104. the first two parameters, where the first parameter is 0.  The
  1105. remaining parameters are the keystrokes to substitute. Extended keys
  1106. are supported -- they have 224 as the first parameter and the scan
  1107. code as the second. Unassigned extended characters are automatically
  1108. mapped to their non-extended counterparts.  Normally a string is used
  1109. rather than numeric arguments. See your DOS manual for the chart of
  1110. keycodes.
  1111.  
  1112. For example, to have F5 do a DIR command, you would execute
  1113.  
  1114. ESC[0;63;"DIR";13p
  1115.  
  1116. To restore the key to its original function, assign it its original codes:
  1117.  
  1118. ESC[0;63;0;63p
  1119.  
  1120. ******************************THE END****************************
  1121.